Thanks for the PR!

• Contributor signed CLA now or in the past
  • If you just signed, leave a comment here with your real name
• PR's commit messages follow the commit message format

If you need to make changes to your pull request, you can update the commit with git commit --amend.
Then, update the pull request with git push -f.

Thanks again for your help!

I've just signed. My name is Michal Charemza.

I'm sorry, but I wasn't able to verify your CLA signature. CLA signature is required for any code contributions to AngularJS.

Please sign our CLA and ensure that the CLA signature email address and the email address in this PR's commits match.

If you signed the CLA as a corporation, please let me know the company's name.

Thanks a bunch!

PS: If you signed the CLA in the past then most likely the email addresses don't match. Please sign the CLA again or update the email address in the commit of this PR.
PS2: If you are a Googler, please sign the CLA as well to simplify the CLA verification process.

Sorry! I thought I had done it. I have now done it. I've also checked the email address is definitely the same as the primary GitHub email address on my account.

Ah... I've just seen at #5311 (comment) that you don't need the CLA for doc changes. In case there is some issue with the CLA: this is just a doc change PR.

I am concerned about the nomenclature used in the following:

A promise's resolution can be deferred by resolving it with another promise. Using this
technique, additional asynchronous functionality can be injected into chains.

It should be apparent on its face that the word "resolve" is used twice in the same sentence to mean different things. "A promises's resolution can be deferred" by "resolving" it to a promise is actually incorrect, what is deferred is not the resolution, but rather the fulfillment of the promise. When you run dForP.resolve(q), you are resolving p, the promise of dForP, not deferring it. What is being delayed is its fulfillment with a value.

This was a raging debate, now well-settled, in the nomenclature wars of Promises A+. Resolution is not one of the "three states," but it is a dynamic status that the fate of the promise has been sealed. Even though the "resolved" promise is in the pending state, until the dependency promise is fulfilled, its fate is sealed to depend on the promise. In any case, as that debate has been resolved in the spec, the terminology of the proposed pull request is incorrect.

The sentence can be corrected in several ways, but replacing "resolution" with "fulfillment." I'm not terribly happy with the use of the word "deferred," since it invites further confusion with the notion of a "defer" object. Perhaps:

You can fix the fate of a promise by resolving it to a value. However, when the value is not presently
available, you can also fix the fate of the promise to the resolution of another promise.
In that case, the first promise is not fulfilled or rejected until the other promise is fulfilled or rejected.
In this way you can create chains of promises, all of which will be fulfilled or rejected upon the
fulfillment or rejection of the last promise in the chain.

@michalc - thanks for this update to the docs.

Can you update your PR taking into account the comments by @wizardwerdna? I think he has a valid point.

Moreover, I personally think this would be more easy to follow if we had a concrete service providing the promises rather than creating abstract promises using deferred. The obvious candidate would be two calls to $http. This has the additional benefit of not encouraging developers to create their own deferred objects when there are promises around already that can be used, which is a common anti-pattern I see often.

If you agree with my comments then could you modify your examples accordingly?

Closing due to lack of response.